home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Extras / Development / RKM_Companion_v2.04 / Clipboard / cbio.doc < prev    next >
Encoding:
Text File  |  1999-10-27  |  5.3 KB  |  187 lines
  1. /*
  2.  * Copyright (c) 1992-1999 Amiga, Inc.
  3.  * 
  4.  * This example is provided in electronic form by Amiga, Inc. for 
  5.  * use with the "Amiga ROM Kernel Reference Manual: Devices", 3rd Edition, 
  6.  * published by Addison-Wesley (ISBN 0-201-56775-X).
  7.  * 
  8.  * The "Amiga ROM Kernel Reference Manual: Devices" contains additional 
  9.  * information on the correct usage of the techniques and operating system 
  10.  * functions presented in these examples.  The source and executable code 
  11.  * of these examples may only be distributed in free electronic form, via 
  12.  * bulletin board or as part of a fully non-commercial and freely 
  13.  * redistributable diskette.  Both the source and executable code (including 
  14.  * comments) must be included, without modification, in any copy.  This 
  15.  * example may not be published in printed form or distributed with any
  16.  * commercial product.  However, the programming techniques and support
  17.  * routines set forth in these examples may be used in the development
  18.  * of original executable software products for Amiga computers.
  19.  * 
  20.  * All other rights reserved.
  21.  * 
  22.  * This example is provided "as-is" and is subject to change; no
  23.  * warranties are made.  All use is at your own risk. No liability or
  24.  * responsibility is assumed.
  25.  *
  26.  */
  27.  
  28.  
  29.  
  30. TABLE OF CONTENTS
  31.  
  32. cbio/CBClose
  33. cbio/CBFreeBuf
  34. cbio/CBOpen
  35. cbio/CBQueryFTXT
  36. cbio/CBReadCHRS
  37. cbio/CBReadDone
  38. cbio/CBWriteFTXT
  39.  
  40.  
  41. cbio/CBClose                                                     cbio/CBClose
  42.  
  43.    NAME
  44.        CBClose() -- Close the clipboard.device
  45.  
  46.    SYNOPSIS
  47.        CBClose()
  48.  
  49.        void CBClose()
  50.  
  51.    FUNCTION
  52.        Close the clipboard.device unit which was opened via
  53.        CBOpen().
  54.  
  55. cbio/CBFreeBuf                                                 cbio/CBFreeBuf
  56.  
  57.    NAME
  58.        CBFreeBuf() -- Free buffer allocated by CBReadCHRS()
  59.  
  60.    SYNOPSIS
  61.        CBFreeBuf( buf )
  62.  
  63.        void CBFreeBuf( struct cbbuf * )
  64.  
  65.    FUNCTION
  66.        Free's a buffer allocated by  CBReadCHRS().  
  67.  
  68. cbio/CBOpen                                                       cbio/CBOpen
  69.  
  70.    NAME
  71.        CBOpen() -- Open the clipboard.device
  72.  
  73.    SYNOPSIS
  74.        ior = CBOpen(unit)
  75.  
  76.        struct IOClipReq *CBOpen( ULONG )
  77.  
  78.    FUNCTION
  79.        Opens the clipboard.device.  A clipboard unit number
  80.        must be passed in as an argument.  By default the unit
  81.        number should be 0 (currently valid unit numbers are
  82.        0-255).
  83.  
  84.    RESULTS
  85.        A pointer to an initialized IOClipReq structure, or
  86.        a NULL pointer if the function fails.
  87.  
  88.    BUGS
  89.        When these clipboard support functions are used with older 
  90.        versions of the Amiga OS (i.e., before V36) a memory loss 
  91.        of 536 bytes will occur due to bugs in the clipboard device.
  92.  
  93. cbio/CBQueryFTXT                                             cbio/CBQueryFTXT
  94.  
  95.    NAME
  96.        CBQueryFTXT() -- Check to see if clipboard contains FTXT
  97.  
  98.    SYNOPSIS
  99.        result = CBQueryFTXT( ior )
  100.  
  101.        int CBQueryFTXT(struct IOClipReq *)
  102.  
  103.    FUNCTION
  104.        Check to see if the clipboard contains FTXT.  If so,
  105.        call CBReadCHRS() one, or more times until all CHRS
  106.        chunks have been read.
  107.  
  108.    RESULTS
  109.        TRUE if the clipboard contains an FTXT chunk, else FALSE.
  110.  
  111.    NOTES
  112.        If this function returns TRUE, you must either call
  113.        CBReadCHRS() until CBReadCHRS() returns FALSE, or
  114.        call CBReadDone() to tell the clipboard.device that
  115.        you are done reading.
  116.  
  117. cbio/CBReadCHRS                                               cbio/CBReadCHRS
  118.  
  119.    NAME
  120.        CBReadCHRS() -- Reads the next CHRS chunk from clipboard
  121.  
  122.    SYNOPSIS
  123.        cbbuf = CBReadCHRS( ior )
  124.  
  125.        struct cbbuf *CBReadCHRS(struct IOClipReq * )
  126.  
  127.    FUNCTION
  128.        Reads, and returns the text in the next CHRS chunk
  129.        (if any) from the clipboard.
  130.  
  131.        Allocates memory to hold data in next CHRS chunk.
  132.  
  133.    RESULTS
  134.        Pointer to a cbbuf struct (see cb.h), or a NULL indicating
  135.        a failure (e.g., not enough memory, or no more CHRS chunks).
  136.    
  137.        ***Important***
  138.  
  139.        The caller must free the returned buffer when done with the
  140.        data by calling CBFreeBuf().
  141.  
  142.    NOTES
  143.        This function strips NULL bytes, however a full reader may 
  144.        wish to perform more complete checking to verify that the 
  145.        text conforms to the IFF standard (stripping data as required).
  146.  
  147.        Under 2.0, the AllocVec() function could be used instead of
  148.        AllocMem() in which case the cbbuf structure may not be
  149.        needed.
  150.  
  151. cbio/CBReadDone                                               cbio/CBReadDone
  152.  
  153.    NAME
  154.        CBReadDone() -- Tell clipboard we are done reading
  155.  
  156.    SYNOPSIS
  157.        CBReadDone( ior )
  158.  
  159.        void CBReadDone(struct IOClipReq * )
  160.  
  161.    FUNCTION
  162.        Reads past end of clipboard file until io_Actual is
  163.        equal to 0.  This is tells the clipboard that we are
  164.        done reading.
  165.  
  166. cbio/CBWriteFTXT                                             cbio/CBWriteFTXT
  167.  
  168.    NAME
  169.        CBWriteFTXT() -- Write a string of text to the clipboard.device
  170.  
  171.    SYNOPSIS
  172.        success = CBWriteFTXT( ior, string)
  173.  
  174.        int CBWriteFTXT(struct IOClipReq *, char *)
  175.  
  176.    FUNCTION
  177.        Write a NULL terminated string of text to the clipboard.
  178.        The string will be written in simple FTXT format.
  179.  
  180.        Note that this function pads odd length strings automatically
  181.        to conform to the IFF standard.
  182.  
  183.    RESULTS
  184.        TRUE if the write succeeded, else FALSE.
  185.  
  186.  
  187.